Skip to content

First pass at documenting assert preprocessor directives#519

Merged
tclune merged 34 commits intoGoddard-Fortran-Ecosystem:developfrom
UCL-ARC:doxygen-improvements
Mar 25, 2026
Merged

First pass at documenting assert preprocessor directives#519
tclune merged 34 commits intoGoddard-Fortran-Ecosystem:developfrom
UCL-ARC:doxygen-improvements

Conversation

@connoraird
Copy link
Copy Markdown

@connoraird connoraird commented Dec 3, 2025 •
edited
Loading

Summary of changes

  • Fixes what appeared to be broken documentation generation.
  • Re organises documentation into what felt like logical pages to me.
  • Adds documentation for assert preprocessor directives and subroutines to the doxygen documentation.

The documentation can be generated by running the following command from within the documentation directory (tested with doxygen version 1.15.0, homebrew)

doxygen doxygen.conf

Notes

There is still a lot to be done on the docs beyond anything I've tried to do. I couldn't find a lot of issues relating to improving the docs but I might have missed them. I would be interested in helping more if needed.

Documenting assertions

I wasn't sure exactly how much detail to include here. I originally started adding an entry for every combination of type/kind that was supported but decided against this due to the amount of maintenance that would be needed. I have now opted for documenting each different base type supported (i.e. INTEGER, REAL, etc) but not down to the detail of INTEGER(INT64), for example.

It is also likely that I have missed out some supported functionality as I found it quite difficult to discover where things where defined in the src. At least one thing I think I have missed is the ability to mix the types of expected and actual values (i.e. @assertEqual(INTEGER expected, REAL, actual), for example). I thought I ought to wait for the input of someone who may know more before I spent too much time writing something that is not true.

@connoraird connoraird mentioned this pull request Dec 3, 2025
Closed
@connoraird connoraird marked this pull request as ready for review December 4, 2025 09:03
@connoraird connoraird requested a review from tclune as a code owner December 4, 2025 09:03
@tclune
Copy link
Copy Markdown
Member

tclune commented Mar 10, 2026

Somehow I missed this PR in December. Or rather probably did not have time and then forgot about it.

Please rebase to develop, and I'll review it this week and fold it into the next release.

@mathomp4
Copy link
Copy Markdown
Collaborator

mathomp4 commented Mar 23, 2026

@connoraird Can you rebase this? We are getting close to make a new release.

@connoraird
Copy link
Copy Markdown
Author

connoraird commented Mar 23, 2026

Sorry. I shall work on this first thing tomorrow.

@mathomp4
Copy link
Copy Markdown
Collaborator

mathomp4 commented Mar 23, 2026

Sorry. I shall work on this first thing tomorrow.

Thanks. We just don't want to lose all your hard work 🙂

connoraird added 23 commits March 24, 2026 09:24
@connoraird
Fix documentation CMakeLists.txt to match documented process
e69eb92
@connoraird
Restructure docs to have different files for each page
fd12e77
@connoraird
Add integrating with CMake to doxygen
79e4081
@connoraird
add how to build a parallel pFUnit test with ctest
6fe234d
@connoraird
Add failure message to preprocessor assertEqual test
76c600e
@connoraird
Remove confusing @note from AssertBasic docstring
fd82e15
@connoraird
Cleanup code blocks for assertions in doxygen pages
88734f4
@connoraird
style change and removing section link from main page
d3f75e7
@connoraird
document @assertEqual
fb2446d
@connoraird
document @AssertTrue
c50932c
@connoraird
document @assertfalse
b252e1e
@connoraird
Update @assertEqual docs to have full reference
8bc94bd
@connoraird
Update @AssertTrue docs to have full reference
ce4d619
@connoraird
Update @assertfalse docs to have full reference
55374cb
@connoraird
Add fortran code block tags
95f35a2
@connoraird
Add ability to collapse assertEqul reference sections
8bc5938
@connoraird
Document @assertLessThan macro
63af174
@connoraird
Remove reference subsubsections
64cee35
@connoraird
Remove large lists of kinds to keep docs more maintainable
ef426fa
@connoraird
Move scalar comparison single statement at top
adff957
@connoraird
Remove fortran from code blocks and combine array and scalar comparisons
ba02b8b
@connoraird
Add docs for assertLessThanOrEqual preprocessor
0514ae0
@connoraird
Add docs for assertGreaterThan preprocessor
2cc415c
@connoraird connoraird force-pushed the doxygen-improvements branch from b6e148d to 2fca6b6 Compare March 24, 2026 09:31
@connoraird
Copy link
Copy Markdown
Author

connoraird commented Mar 24, 2026

I have now rebased. @tclune @mathomp4 Should this also be pointing at develop?

@connoraird connoraird changed the base branch from main to develop March 24, 2026 09:34
@tclune
Copy link
Copy Markdown
Member

tclune commented Mar 24, 2026

I have now rebased. @tclune @mathomp4 Should this also be pointing at develop?

Yes - thanks for catching that.

@mathomp4
Copy link
Copy Markdown
Collaborator

mathomp4 commented Mar 24, 2026 •
edited
Loading

@connoraird I think you might need to tweak bin/funit/tests/test_parser_assertions.py. The CI is unhappy:

      Start 19: unit_test_processor
    Test #19: unit_test_processor ........................***Failed    0.06 sec
...F...............s............
======================================================================
FAIL: testMatchAtAssertEqual (funit.tests.test_parser_assertions.TestParserAssertions.testMatchAtAssertEqual)
Check that a line starting with '@assertEqual' is detected
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/Users/runner/work/pFUnit/pFUnit/bin/funit/tests/test_parser_assertions.py", line 36, in testMatchAtAssertEqual
    self.assertEqual("  call assertEqual(1, 2, \"failure message\"&\n", parser.outLines[1])
    ~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
AssertionError: '  call assertEqual(1, 2, "failure message"&\n' != '  call assertEqual(1, 2, "failure message", &\n'
-   call assertEqual(1, 2, "failure message"&
+   call assertEqual(1, 2, "failure message", &
?                                           ++


----------------------------------------------------------------------
Ran 32 tests in 0.006s

This looks like it might have something to do with #533 from @tclune ? I'm not sure. I mean, it's like there is either a space missing or a space now needed.

I think you need to add a comma and a space?

@connoraird
Copy link
Copy Markdown
Author

connoraird commented Mar 24, 2026

I think you need to add a comma and a space?

Hopefully that's done it @mathomp4?

@mathomp4
Copy link
Copy Markdown
Collaborator

mathomp4 commented Mar 24, 2026

I think you need to add a comma and a space?

Hopefully that's done it @mathomp4?

Forgot to press the "Run workflows" button. We shall see soon.

Also, could you maybe add an entry to our changelog for your PR?

@mathomp4
Copy link
Copy Markdown
Collaborator

mathomp4 commented Mar 24, 2026

Sigh. I might turn off that "approve fork repo workflows" thing. I mean, it's just github tests!

Running one more time!

@tclune tclune merged commit 58b51b8 into Goddard-Fortran-Ecosystem:develop Mar 25, 2026
16 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@tclune tclune tclune approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@connoraird @tclune @mathomp4